Repository navigation
fix(qe): unfold QE phases and f orbitals with the core's harmonics - #305
Conversation
55391e3 to
ed5c0ab
Compare
|
VERDICT: PASS+NOTES Reviewed SHA: What I ranI used detached worktrees at the head, at origin/dev, and at the middle commit 85c30d1, each set up with
Findings (none blocking)
|
|
VERDICT: PASS+NOTES Reviewed SHA ed5c0ab (origin/dev 4de5cc0 is an ancestor, so head equals head merged with dev). Lane: Live + red/green + gates. Independent verifier; I did not write this PR. Sign convention against QE source. I fetched Reference validated from raw
Public API, unfolded IBZ vs nosym. My own script (not compare.py) calls
The head residuals are within the reference's own symmetry spread (2.9e-4). Running pyprocar wrote no files into the calc copies. Red/green and mutants.
Gates at head. All of these ran through
Notes (none blocking).
|
|
VERDICT: PASS+NOTES Reviewed SHA: SetupI used detached worktrees at the head, at Callers of
|
| fixture | origin/dev | ed5c0ab | head |
|---|---|---|---|
| spin-polarized-colinear, peak | 3.595 to 3.596 GiB | 9.229 to 9.235 GiB | 3.782 to 3.786 GiB |
| non-spin-polarized, peak | 2.005 to 2.009 GiB | 4.845 to 4.848 GiB | 2.114 to 2.117 GiB |
| spin-polarized, time (load about 8) | 2.94 to 3.00 s | 6.62 to 6.85 s | 3.59 to 3.74 s |
| non-spin-polarized, time (load about 8) | 0.96 to 0.97 s | 2.77 to 3.22 s | 1.39 to 1.68 s |
- Surfaces are identical across all three builds. The points sha256 is
80fef54c…(3000 points) and02de5a9e…(1540 points), and the faces sha256 match too. FermiSurface.from_ebsalone takes 0.78 to 0.80 s on dev and on head (non-spin-polarized) and 2.56 to 2.63 s (spin-polarized), so the remaining difference is infrom_code, which is round-1 work.- A first pass at load about 20 gave the same memory and slower times.
Red/green and mutants
test_fermisurface_phases.py::test_fermi_surface_pads_the_projections_but_not_the_phases:- Fails on dev's library and on
ed5c0aba's library, withassert Property(name=projected_phase, value=(2744, 1, 1, 1, 1)…) is None. - Passes at head.
- Mutant that drops the phase from
selfbefore the deepcopy: the test fails onassert ebs.projected_phase is not None.
- Fails on dev's library and on
test_qe_mesh_bands_are_eigenvectors_of_their_little_group[both]:- Fails on dev's library (
projected_phaseis None). - Passes at
ed5c0abaand at head. - Mutant with
_core_harmonic_signsreturning ones (flip reverted): both cases fail, with max residual 0.99999 and 0.99997. - Mutant with
(-1)**min place of(-1)**(m//2): both cases fail too.
- Fails on dev's library (
- My replica of the test, with the identity skipped, gives max residual 3.59e-4 over 52466 checks (non-spin-polarized) and 4.16e-4 over 104884 (spin-polarized). This matches the body.
red_green.py origin/dev: ok. The 2 non-data added tests fail on base for the stated reasons.
Gates at head (verify.sh exec, -n 4)
pytest -m "not data": 2010 passed, 2 skipped, exit 0.-m data: head 408 passed, 1 skipped, exit 0. origin/dev 403 passed, 1 skipped, exit 0. The +5 are this PR's data cases.- basedpyright: 0 errors, 0 warnings, exit 0.
ruff_new_violations.pycheck and format vs origin/dev: ok.- ruff F821/F822/F823/NPY201: all checks passed.
gh pr checks 305: format, lint, red-green, test and typecheck pass, on run 37241870465 with headSha 8e35d37.
PR body claims
paddrops phases;from_codemesh andoriginal_ebskeep them: confirmed.- Memory table: confirmed to 0.01 GiB.
- Times: confirmed for dev,
ed5c0abaand head spin-polarized. Head non-spin-polarized measured 1.39 to 1.68 s against the stated 1.22 s, under load (see note 2). - Same surfaces, 3000 and 1540 points: confirmed.
from_ebs0.79 s on both: confirmed.- Little-group test (residuals, check counts, 1.0 without the flip, fails on dev): confirmed.
- Pad test fails at
ed5c0abawith a(2744,1,1,1,1)phase: confirmed. - Gates (2010/2, 408/1 vs 403, basedpyright 0, ruff ok): confirmed.
- IBZ vs nosym energies. I parsed both runs'
atomic_proj.xmlindependently, with Ry to eV and the 48 cubic operations. The images give 5.53e-6 eV (SrVO3) and 1.31e-5 eV (LaVO3): confirmed. At the IBZ k-points, 1.1e-12 and 4.8e-10 eV hold only for bands 1 to 26 and 1 to 30 (see note 1). - The rest of the body is round-1 content. The round-1 verdicts already cover it, and the delta does not change it.
Notes (none blocking)
- Band windows of the IBZ k-point energy figures. The body's "4.8e-10 eV (LaVO3)" holds for bands 1 to 30. Band 31, which is inside the body's own 1 to 31 window, differs by 2.0e-8 eV, and band 32 by 4.1e-6 eV. SrVO3's 1.1e-12 holds for bands 1 to 26; bands 28 to 30 reach 2.1e-11.
features/parsers.mdsays "5e-10 eV at the IBZ k-points" and names no window. Suggested fix: state the window, or quote 4.1e-6 eV for LaVO3 bands 1 to 33. - Head non-spin-polarized time. I measured 1.39 to 1.68 s at load about 8, against the stated 1.22 s. The difference is inside
from_code, andfrom_ebsis equal on dev and head, so the round-2 change does not cause it. pad's defaultinplace=Truenow deletesprojected_phasefrom the caller's own mesh. No library caller usesinplace=True, and the docstring says so. A user who callsebs.pad()directly loses phases that were already wrong after a pad.expand_kpoints_to_supercell_by_axesstill pads phases without the G.tau factor. It is dead code inpyprocar/(round-1 note 3, remainder).- Round-1 note 5 is resolved. The new data test guards the flip on the real fixtures.
- Round-1 notes 2, 4 and 6 are unchanged and out of scope. They cover semicore cross terms, Abinit phase signs, and the QE spin-polarized
unfoldbroadcast error. - Environment. The main checkout's pixi.lock differs from origin/dev's, so local gates ran on a drifted env. CI is green.
Since #298 the QE parser names its orbitals as projwfc.x prints them. ibz2fbz did not know the three f labels fzx2-zy2, fx3-3xy2 and f3yx2-y3, so it dropped a QE mesh's phases and left f unrotated. Against QE 7.5 nosym runs, V eg weights were off by 0.30 and La f by 1.0. ORBITAL_ALIASES now maps the three labels. QE's real harmonics carry the sign (-1)^|m| (upflib/ylmr2.f90), and the core's carry none. The parser now writes the phases over the core's harmonics. Without that the kept phases unfold with wrong signs on px, py, dxz, dyz, fxz2, fyz2, fx3-3xy2 and f3yx2-y3, and phase products are off by up to 1.4. Refs #293
The harmonic sign flip needs projwfc.x's orbital list. When spd_phase is set without it, position_gauge_phase returned the phases with no exp(-2 pi i k.tau) factor, so test_ebs_phases_use_bloch_sums_over_atom_positions failed. Now the parser skips only the flip, and the Bloch factor always applies. The signs and the Bloch factor are combined first and applied in one multiply, so the parser no longer makes a second full-size copy of the phase array. Refs #293
QE meshes keep their phases since the sign fix, and the Fermi-surface path padded them: 9.2 GiB peak on the spin-polarized SrVO3 fermi fixture. Nothing reads phases on a padded mesh, and copies at k + G would be wrong because position-gauge phases are not periodic in k. Refs #293
The data test checked only warnings and that phases were kept, so it passed with the sign flip reverted. Each nondegenerate band with V weight must be an eigenvector of the orbital rotation of every operation that fixes its k-point: max residual 3.6e-4 and 4.2e-4 over 52466 and 104884 checks by non-identity operations, against 1.0 without the flip. Refs #293
…he QE reference The 2.9e-4 LaVO3 figure holds over bands 1 to 31 of 34, and the 1e-9 eV energy agreement only at the IBZ k-points. Note the pad memory figure. Refs #293
8e35d37 to
514b6ee
Compare
Why
A user who loads a symmetry-reduced QE calculation as a mesh (
ElectronicBandStructureMesh.from_code("qe", ...), as the Fermi-surface plots do) gets two warnings on dev. The phases are dropped and the f shell is not rotated, so orbital-resolved d and f weights at the unfolded k-points are wrong. Against a QE nosym run, V eg weights are off by 0.30 and La f weights by 1.0.There are two causes:
ORBITAL_ALIASES(pyprocar/core/ebs.py:2096) does not map the three f labelsfzx2-zy2,fx3-3xy2andf3yx2-y3. As a result,unrotated_orbitalsreports f as a partial shell, and ibz2fbz drops the phases (ebs.py:2324).pyprocar/io/qe/parser.py:690), so once the phases are kept they unfold with wrong signs. QE 7.5upflib/ylmr2.f90sets the sign at line 78 (ylm(ig,4) = -sent/sqrt(2)) and line 94 (the minus sign in the Q(l,l) recursion). Lines 125 and 129 multiply by cos(m phi) and sin(m phi). projwfc.x's m = 1, 2, 3, ... is |m| = 0, 1, 1, 2, 2, ..., so px, py, dxz, dyz, fxz2, fyz2, fx3-3xy2 and f3yx2-y3 have the opposite sign.What changed
ORBITAL_ALIASESmaps the three QE f labels to the core'sfzx2,fx3andfy3x2.QEParser.position_gauge_phasemultiplies the phases by the harmonic signs (_core_harmonic_signs) and the Bloch factor in one pass. The Bloch factor still applies when no projwfc.x orbitals are known.ElectronicBandStructureMesh.paddropsprojected_phase. Kept QE phases made the Fermi-surface path pad them (generate_band_isosurfaces,pyprocar/core/fermisurface.py:1016, andBandStructure2D.from_ebs,pyprocar/core/bandstructure2D.py:549), and nothing reads phases on a padded mesh. The padded copies were also wrong: phases with exp(i k.(R + tau)) Bloch sums are not periodic in k, so a copy at k + G needs exp(-2 pi i G.tau). The mesh fromElectronicBandStructureMesh.from_codeand theoriginal_ebsof aFermiSurfacekeep their phases.Scope
spd_phaseisNonefor spinors).Fermi-surface memory
Peak RSS (
resource.getrusage(RUSAGE_SELF).ru_maxrss, GiB) and wall time ofFermiSurface.from_code("qe", data/codes/qe/7.2/SrVO3/<mag>/fermi), 3 runs each, one job at a time, insidebwrapwith the data read-only:Memory spread across runs is under 0.01 GiB. The round-1 times ran under a load average of about 8; the dev and head rows ran back to back at about 3. All three builds draw the same surfaces (sha256 of
fs.pointsequal, 3000 and 1540 points).What is left against dev is the work this PR adds on purpose.
ElectronicBandStructureMesh.from_codetakes 0.47 s against 0.18 s on non-spin-polarized, and cProfile puts the difference in_turn_projections(0.43 s against 0.04 s), which now mixes phases into the d weights.FermiSurface.from_ebstakes 0.79 s on both. The 0.10 and 0.18 GiB of extra memory match the phase array the unpadded mesh keeps (complex128[4096, 25, nspin, 5, 16], 0.12 and 0.24 GiB).Blast Radius
The sign and alias changes touch only QE phases and names that no other parser uses. VASP names (
fy3x2,fx3,fzx2) are not affected. Weights from QE path calculations do not change, because the flip changes only signs, and weights are |c|^2. Thepadchange applies to every code: a padded mesh (theebsof aFermiSurfaceorBandStructure2D) has noprojected_phase, which also saves memory on VASP LORBIT=12 meshes.Verification
Independent reference. I made QE 7.5 runs of SrVO3 and spin-polarized LaVO3 at 6x6x6: one IBZ run (48 operations, 20 k-points) and one nosym run (216 k-points) from the same SCF density. The runs, the scripts and the results are in
~/Documents/lllangWV-Projects/DFT/pyprocar-293-qe-sign.validate.pychecks the reference without pyprocar:validate.pyconverted the Rydberg energies ofatomic_proj.xmlwith the Hartree factor and compared only the IBZ k-points. Both are fixed there.)atomic_proj.xmlto its print precision.Unfolded IBZ against nosym (
compare_all.sh). The table gives the maximum absolute difference over all degenerate-band groups (1 meV) below the top four bands: bands 1 to 26 of 30 for SrVO3 and 1 to 31 of 34 for LaVO3 (TOP_MARGIN=3gives the same numbers). With LaVO3's band 32 included (TOP_MARGIN=2 python compare.py lavo3 head_top2), the all atom-pair figure is 2.5e-3. The top of a truncated band set is unconverged, and the LaVO3 nosym nscf ran withconv_thr = 1e-8against 1e-10 for the IBZ nscf; the SrVO3 inputs differ only innosymandnoinv. The weight and intra-atom columns list s, p, d and f.Without the flip the weights still match, because cubic operations only permute signed orbitals. The phases do not match.
Tests.
test_qe_phase_convention.py::test_qe_phases_unfold_to_the_coefficients_at_each_grid_pointgoes throughQEParser.ebswith QE-signed coefficients of a known field on a 4x4x4 cubic grid.UserWarning: projected_phase is dropped(thered-greenjob agrees).test_ebs_phases_use_bloch_sums_over_atom_positionsfails.The data test
test_qe_mesh_rotates_every_orbital_and_keeps_collinear_phasesloads the three QE SrVO3fermimeshes. On dev it fails on the two warnings. With this PR there is no user warning, and the two collinear meshes keep their phases.The data test
test_qe_mesh_bands_are_eigenvectors_of_their_little_groupguards the flip on the real fixtures. On the two collinear meshes, each nondegenerate band (gap over 1e-3 eV) with V weight over 0.05 must be an eigenvector of the orbital rotation of every cubic operation that fixes its k-point. V maps onto itself up to a lattice vector, so the Bloch factor is one common phase. At this head the max residual is 3.6e-4 (non-spin-polarized) and 4.2e-4 (spin-polarized) over 52466 and 104884 non-identity checks. With_core_harmonic_signsreturning ones it is 1.0 and both cases fail. On dev the phases are dropped, so it fails onprojected_phase is None.test_fermisurface_phases.py::test_fermi_surface_pads_the_projections_but_not_the_phasesbuilds a 10x10x10 mesh with phases and callsFermiSurface.from_ebs(ebs, padding=2). The padded mesh hasprojectedof shape(14**3, 1, 1, 1, 1)and noprojected_phase, and the input mesh keeps exp(2 pi i kx). At ed5c0ab it fails: the padded mesh holds a(2744, 1, 1, 1, 1)phase.Gates at 8e35d37 (
verify.sh exec):pytest -m "not data" -n 82010 passed, 2 skipped;pytest -m data -n 4408 passed, 1 skipped (origin/dev: 403 passed; the 5 extra are this PR's data cases); basedpyright 0 errors;ruff_new_violations.pycheck and format ok; ruff F821/F822/F823/NPY201 ok.Refs #293